home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / LANG / C / LIB / DESK / CORE / Desk / h_doc / Slider < prev    next >
Text File  |  1996-05-21  |  12KB  |  311 lines
  1. /*
  2.     ####             #    #     # #
  3.     #   #            #    #       #          The FreeWare C library for 
  4.     #   #  ##   ###  #  # #     # ###             RISC OS machines
  5.     #   # #  # #     # #  #     # #  #   ___________________________________
  6.     #   # ####  ###  ##   #     # #  #                                      
  7.     #   # #        # # #  #     # #  #    Please refer to the accompanying
  8.     ####   ### ####  #  # ##### # ###    documentation for conditions of use
  9.     ________________________________________________________________________
  10.  
  11.     File:    Slider.h
  12.     Author:  Copyright © 1994 Peter Gaunt
  13.     Version: 1.00 (12 Mar 1994)
  14.     Purpose: Provide a clean way of using 'slider' icons.  These routines 
  15.                are more general-purpose, friendly and efficient that those
  16.                found in the Icon library.  (The Icon slider functions are left
  17.                in for backwards compatibility at the moment - you should
  18.                use these functions in preference).
  19. */
  20.  
  21. #ifndef __Desk_Slider_h
  22. #define __Desk_Slider_h
  23.  
  24. #ifdef __cplusplus
  25.     extern "C" {
  26. #endif
  27.  
  28.  
  29. #ifndef __Desk_Core_h
  30.     #include "Desk.Core.h"
  31. #endif
  32.  
  33. #ifndef __Desk_WimpSWIs_h
  34.     #include "Desk.WimpSWIs.h"
  35. #endif
  36.  
  37. #ifndef __Desk_Sprite_h
  38.     #include "Desk.Sprite.h"
  39. #endif
  40.  
  41.  
  42. #define Desk_SLIDER_MAX 100000
  43.  
  44. /*
  45. To work, sliders need a base icon. This should be a non-text, non-sprite icon
  46. with an unfilled background. The window should have its auto-redraw flag clear.
  47. They need a minimal amount of co-operation from the rest of the program in
  48. order to be redrawn after redraw events (this basically just involves calling
  49. Desk_Slider_Redraw inside a redraw loop). The boundary for the slider icon should
  50. not overlap any part of the window which also needs help to be redrawn.
  51.  
  52. Although sliders maintain their current value internally on a scale of
  53. 0 - Desk_SLIDER_MAX, the values returned when Slider functions are called are always
  54. in "user units" which are set within whatever limits suit your program best
  55. (within reason of course).
  56.  
  57. Slider functions need Desk_screen_delta info to be kept up to date
  58. Make sure the mode change event is enabled and Desk_Handler_ModeChange is called
  59.  
  60. */
  61.  
  62.  
  63.  
  64.  
  65. typedef struct
  66. {
  67.   Desk_window_handle window;
  68.   Desk_icon_handle   icon;
  69.  
  70.   int value;
  71.  
  72.   struct
  73.   { int         min;
  74.     int         max;
  75.   } limits;
  76.  
  77.   struct
  78.   { int foreground;
  79.     int background;
  80.   } colour;
  81.  
  82.   struct
  83.   { int x;
  84.     int y;
  85.   } border;
  86.  
  87.   struct
  88.   { Desk_sprite_areainfo *spritearea;
  89.     Desk_sprite_header   *sprite;
  90.   } knob;
  91.  
  92.   struct
  93.   { int  vertical  :1;
  94.     int  rgb       :1;
  95.     int  dragging  :1;
  96.     int  clickstop :1;
  97.     int  reserved  :28;
  98.   } flags;
  99.  
  100.   int ( *update )( void *, void * );
  101.   int reference;
  102. } Desk_slider_info;
  103. /*
  104.     The slider functions use this structure extensively.
  105.     
  106.     The elements are as follows :
  107.  
  108.     window: handle of window containing the slider
  109.     icon  : handle of base icon within the window. Should have unfilled 
  110.             background.
  111.             If you want to be able to drag the slider you should normally 
  112.             set the icon's button type to click (type 3). You then call 
  113.             Desk_Slider_Drag when the icon is clicked.
  114.  
  115.     value: slider functions use values between 0 & Desk_SLIDER_MAX which are
  116.            converted to user units between limits.min and limits.max when
  117.            returned to calling functions. Set this status.value to
  118.            Desk_SLIDER_MAX +1 when initialising the slider.
  119.  
  120.     limits.min
  121.     limits.max: Values returned when the slider is at its minimum or maximum
  122.                 extent. Other slider positions return intermediate values.
  123.                 The slider is clamped to these values.
  124.  
  125.     colour.foreground
  126.     colour.background: Foreground and background colours of the slider.
  127.                        Set colours to -1 if not wanting a visible slider.
  128.                        See also flags.rgb below
  129.     border.x
  130.     border.y: size of blank border which will be left between the slider and
  131.               the base icon boundary. OS units.
  132.               Note that if the base icon has a border then setting the slider
  133.               borders to 0 causes the icon's border to flicker when the 
  134.               slider is updated. Setting a slider border avoids this. The 
  135.               slider border needed to prevent flicker depends on the type of
  136.               border which the icon has. A value of 4 suffices for most of 
  137.               the standard icon borders. A value of 12 produces sliders 
  138.               similar to those in the RISC OS 3 Style Guide if the icon has 
  139.               an r2 type border. Setting borders greater than half the size 
  140.               of the icon produces odd effects...
  141.  
  142.     knob: Not used at present but may be used in future versions to specify
  143.           a sprite to be used as a knob. For now set knob.spritearea to NULL
  144.           to indicate no knob.
  145.  
  146.     flags.vertical: If set then slider is vertical. If clear then it is
  147.                     horizontal.
  148.     flags.rgb:      If clear then colour.foreground & colour.background refer
  149.                     to Wimp colours 0-15. If set then they refer to an RGB
  150.                     palette suitable for passing to ColourTrans (0xBBGGRR00).
  151.     flags.dragging: This is set by Desk_Slider_Drag while it is dragging a slider.
  152.                     Set this to zero when initialising slider.
  153.     flags.clickstop:If clear then slider is dragged as smoothly as possible.
  154.                     If set then slider jumps between exact user values as it
  155.                     is dragged, i.e. slider will only be redrawn when user 
  156.                     value changes.
  157.     flags.reserved: For future expansion. Set this to zero.
  158.  
  159.     update: If this is not set to NULL then it is a pointer to a function
  160.             which will be called if the slider value (in user units not
  161.             internal units) changes during a call to Desk_Slider_SetValue
  162.             or Desk_Slider_Drag.
  163.  
  164.             Providing an update function is useful since it allows you
  165.             to centralise other operations, such as updating a text icon
  166.             showing the slider's value, regardless of whether the slider
  167.             moves because of a drag or a call to Desk_Slider_SetValue. It is
  168.             also useful for continually monitoring the current value during
  169.             a drag operation which otherwise you wouldn't know until the
  170.             drag finished.
  171.  
  172.             The function should take two arguments. The first is a
  173.             pointer to a Desk_slider_info structure. When the function is
  174.             called this argument is a pointer to the slider currently
  175.             being dealt with.
  176.  
  177.             The second argument is a pointer to any data you wish.
  178.             You pass a pointer (which can be NULL) to the data to
  179.             Desk_Slider_SetValue or Desk_Slider_Drag when you call them and it
  180.             gets passed on to the update function when/if it is called.
  181.             This argument can be useful, for example, for passing
  182.             information to your update function to indicate just what
  183.             operation is currently being performed (e.g. to let it
  184.             distinguish between a call to Desk_Slider_SetValue and a call to
  185.             Desk_Slider_Drag).
  186.  
  187.             The function should return non-NULL if it wants the drag
  188.             function to stop dragging. This allows you to, for example,
  189.             stop the slider going above or below a maximum or minimum
  190.             value, independently of limits.min and limits.max.
  191.  
  192.     reference: You may use this for any purpose you like. If you set up more
  193.                than one slider, it is useful to give each a separate 
  194.                reference so that your update function (if any) can 
  195.                distinguish between them without having to check the window &
  196.                icon handles.
  197. */
  198.  
  199.  
  200.  
  201.  
  202.  
  203. extern void    Desk_Slider_Redraw(Desk_slider_info *slider, Desk_wimp_rect *clipwindow);
  204. /*    
  205.   Inputs:   slider - the slider info for this slider.
  206.               clipwindow - the area of the window being redrawn (in screen
  207.               coordinates).
  208.   Returns:  An error pointer, or NULL if no errors occured.
  209.   Purpose:  Redraws a slider icon - call this function from within your 
  210.               redraw loops.
  211.             If clipwindow != NULL then does nothing if slider is outside 
  212.             clip window.
  213.   Errors:   Unable to use the colour indicated in 'slider'.
  214.   SeeAlso:  Desk_Slider_ReadValue; Desk_Slider_SetValue; Desk_Slider_Drag
  215. */
  216.  
  217.  
  218.  
  219.  
  220.  
  221. extern int Desk_Slider_ReadValue( Desk_slider_info *slider );
  222. /*
  223.   int Desk_Slider_ReadValue(Desk_slider_info *slider);
  224.     
  225.   Inputs:   slider - the slider info for this slider.
  226.   Returns:  The current slider value, in user units.
  227.   Purpose:  Returns current slider setting in user units.
  228.             (i.e. between slider->limits.min and slider->limits.max)
  229.   SeeAlso:  Desk_Slider_SetValue; Desk_Slider_Drag; Desk_Slider_Redraw
  230. */
  231.  
  232.  
  233.  
  234.  
  235.  
  236. extern void    Desk_Slider_SetValue(Desk_slider_info *slider,
  237.                                  int value,
  238.                                  int *valueset,
  239.                                  void *ref );
  240. /*
  241.   Desk_os_error *Desk_Slider_SetValue(Desk_slider_info *slider,
  242.                             int value,
  243.                             int *valueset,
  244.                             void *ref );
  245.     
  246.   Inputs:   slider - the slider info for this slider.
  247.               value  - the value (in user units) that the slider should be
  248.                          set to.
  249.               ref    - a reference to pass to the update callback funtion.
  250.   Outputs:  valueset - if not NULL, this is updated to hold the value
  251.                        actually the slider is actually set to (this can be
  252.                        different to 'value', e.g. if value is outside the
  253.                        slider limits).
  254.   Returns:  Standard error block or NULL if no error occurs.
  255.   Purpose:  Sets slider to value in value (user units).
  256.               If the slider is being dragged (i.e. if slider->status.dragging 
  257.               is set) then the function does nothing.
  258.  
  259.             The value is clamped to numbers between slider->limits.min and
  260.             slider->limits.max.
  261.  
  262.             The slider->update function (if any) will be called if the value
  263.             has changed.
  264.  
  265.             Can also be used to alter other settings (e.g. colour) by 
  266.             directly changing the slider structure before calling.
  267.   Errors:   An error is returned if there is a problem accessing or
  268.               redrawing the icon.
  269.   SeeAlso:  Desk_Slider_ReadValue; Desk_Slider_Drag; Desk_Slider_Redraw
  270. */
  271.  
  272.  
  273.  
  274.  
  275.  
  276. extern void    Desk_Slider_Drag(Desk_slider_info *slider,
  277.                              int *closed,
  278.                              int *value,
  279.                              void *ref);
  280. /*
  281.   Desk_os_error *Desk_Slider_Drag(Desk_slider_info *slider,
  282.                         Desk_bool *closed,
  283.                         int *value,
  284.                         void *ref )
  285.     
  286.   Inputs:   slider - the slider info for this slider.
  287.               ref    - a reference to pass to the update callback funtion.
  288.   Outputs:  closed - if not NULL, and the window is closed during the drag,
  289.                          then closed is set to Desk_bool_TRUE.
  290.               value  - if not NULL, then it is set to the slider value (in
  291.                          user units) on exit.
  292.   Returns:  Standard error block, or none if no errors encountered.
  293.   Purpose:  Drag a slider. Call when slider's base icon is clicked on.
  294.               Polls the Wimp, grabbing NULL events but passing the rest on to 
  295.               Desk_Event_Process.
  296.               Exits when dragging stops or the slider->update function (if any)
  297.               returns a non-NULL value.
  298.               Also exits if window is closed while dragging (see Outputs).
  299.   Errors:   An error is returned if there is a problem accessing or
  300.               redrawing the icon.
  301.   SeeAlso:  Desk_Slider_SetValue; Desk_Slider_ReadValue; Desk_Slider_Redraw
  302. */
  303.  
  304.  
  305. #ifdef __cplusplus
  306. }
  307. #endif
  308.  
  309.  
  310. #endif
  311.